home *** CD-ROM | disk | FTP | other *** search
/ MacFormat 1995 January / macformat-020.iso / Shareware City / Education / RLaB / help / FUNCTION < prev    next >
Encoding:
Text File  |  1994-07-30  |  8.6 KB  |  315 lines  |  [TEXT/ttxt]
  1. FUNCTION:
  2.  
  3.     This help file covers several aspects of functions:
  4.  
  5.         1) Introduction
  6.  
  7.         2) Function arguments
  8.  
  9.         3) Function return values
  10.  
  11.         4) Function recursion
  12.  
  13.         5) Function variable scoping
  14.  
  15.         6) Special topics        
  16.  
  17.     1) Introduction ------------------------------------------------
  18.  
  19.     Functions are an essential part of the language. Learning how
  20.     to create and use functions will greatly add to the benefits
  21.     of using RLaB. 
  22.  
  23.     It is important to remember that functions adhere to the RLaB
  24.     rule: "everything is a variable". Functions are variables, and
  25.     like the other types or classes of variables in RLaB can be
  26.     printed (although it will be hard to understand the output),
  27.     copied, and renamed. Functions cannot act as operands to
  28.     numeric operators, although the result of the function usually
  29.     can. Since function calls are evaluated "in-place" they can be
  30.     used within other expressions, for example:
  31.  
  32.     > sin(cos(1.0))
  33.         0.514
  34.  
  35.     > sin( [ cos(0.3), sqrt(cos(0.3)) ] )
  36.         0.817      0.829  
  37.  
  38.  
  39.     The syntax used for function definition is a little unusual...
  40.  
  41.     Example:
  42.  
  43.     > sum = function (s) 
  44.       {
  45.         local(i, Sum);
  46.         Sum = 0;
  47.         for(i in 1:size(s)) {
  48.           Sum = Sum + s[i];
  49.         }
  50.         return Sum;
  51.       };
  52.     >
  53.  
  54.     creates a function, and assigns it to the variable `sum'.
  55.     Sum is invoked like:
  56.  
  57.     > sum( [1,2,3,4,5] )
  58.         15
  59.  
  60.     2) Function arguments ------------------------------------------
  61.  
  62.     RLaB supports both "pass by reference" and "pass by value" for
  63.     passing arguments to a function. 
  64.  
  65.     Pass by reference means that the argument can be modified in
  66.     the caller's scope. Pass by value means that a function cannot
  67.     modify variables in the caller's scope - essentially, an
  68.     argument that is passed by value is copied, and the copied
  69.     value is passed to the function to operate on.
  70.  
  71.     Pass by reference can be considered the default behavior,
  72.     since it takes no special effort on the user's part. Pass by
  73.     value is achieved by declaring function arguments to be
  74.     local. For example:
  75.  
  76.     // Pass by reference
  77.  
  78.     > myf = function ( A ) { A = "changed"; return A; }
  79.         <user-function>
  80.     > B=10;
  81.     > myf(B);
  82.     > B
  83.      B =
  84.     changed
  85.  
  86.     // Pass by value
  87.     > myf = function ( A ) { local (A) A = "changed"; return A; }
  88.         <user-function>
  89.     > B=10;
  90.     > myf(B);
  91.     > B
  92.      B =
  93.            10
  94.  
  95.     In the previous example B, a variable in the global workspace,
  96.     is changed by myf (pass by reference). In the second part of
  97.     the example, the function argument A, is redeclared to be
  98.     local. This redeclaration forces the function argument to be
  99.     passed by value.
  100.  
  101.     One advantage of this behavior is that users can create
  102.     functions and selectively decide which variables should be
  103.     passed by reference, and which should be passed by value.
  104.  
  105.                 * * *
  106.  
  107.     You do not have to call a function with the same number of
  108.     arguments specified in the definition. If you invoke a
  109.     function with more arguments than declared, the result is an
  110.     error. If you call the function with less arguments than
  111.     declared, RLaB will pad the argument list with UNDEFINED,
  112.     objects. Additionally, commas may be used to "skip" arguments
  113.     that are unnecessary. for each argument that is "skipped" an
  114.     UNDEFINED variable is passed to the function during execution.
  115.  
  116.     UNDEFINED arguments can be detected with the exist function,
  117.     for example: 
  118.  
  119.           if (!exist (ARG))
  120.           {
  121.             ARG = 0;    // Initialize undefined argument
  122.           }
  123.     
  124.                 * * *
  125.     Lists can be used to get the effect of variable argument
  126.     lists. If you are not familiar with lists, then now would be a
  127.     good time to `help LIST'. A function can take a list as an
  128.     argument and then pull the actual number of list elements, and
  129.     their values, from the list when the function is called. For
  130.     example:
  131.  
  132.     > vlistf = function( l )
  133.       {
  134.         local(i,x);
  135.  
  136.         printf( "number of elements in variable arg-list = %i\n", size(l) );
  137.       
  138.         // Pull each element from the list
  139.       
  140.         for( i in 1:size(l) )
  141.         {
  142.           x = l.[i];
  143.           // now do something with x
  144.         }
  145.       };
  146.     > vlistf( << "string"; [1,2;3,4] >> )
  147.     number of elements in variable arg-list = 2
  148.     
  149.                 * * *
  150.  
  151.     Functions can take other functions as arguments, for example:
  152.  
  153.     > trick = function ( a , b )
  154.       {
  155.         a(b)
  156.       };
  157.     > trick( eye, [3,3] );
  158.      matrix columns 1 thru 3
  159.                1           0           0
  160.                0           1           0
  161.                0           0           1
  162.  
  163.     Note that the function name, passed as an argument, did not
  164.     need quotes. This is so because functions are variables in the
  165.     same sense as scalars, strings, and matrices. The variable a
  166.     in the previous function example refers to the function eye,
  167.     since function args are passed by reference.
  168.  
  169.     3) Function return values --------------------------------------
  170.  
  171.     All functions return a value, although the return statement is
  172.     optional. If a return statement is not used, then the function
  173.     will return 0 (zero) to the calling environment. If the return
  174.     statement is used, the the result of the return statement is
  175.     passed back to the calling environment.
  176.  
  177.     Functions can only return a single entity to the calling
  178.     environment. If it is necessary to return more than one
  179.     entity, a list can be used to group multiple entities together
  180.     for return.
  181.  
  182.     Example:
  183.  
  184.     We want to write a function that creates a set of matrices (a
  185.     state-space model). We will write such a function, and group
  186.     the separate matrices together in a list.
  187.  
  188.     > ss = function( w )
  189.       {
  190.          local(A, B, n);
  191.         n = size( w )[1];
  192.         A = [ zeros(n,n), eye(n,n);
  193.               -w;         zeros(n,n) ];
  194.         B = ones(n,n);
  195.      
  196.          return << A = A; B = B >>;
  197.       };
  198.     >
  199.  
  200.     The return statement creates the list, and assign the names
  201.     `A' and `B' to it's members.    
  202.  
  203.     Since functions are evaluated "in-place" their return values
  204.     can be manipulated in the usual ways, for example:
  205.  
  206.     > eig(symm(rand(3,3))).val
  207.      val =
  208.        -0.937      0.571       1.81  
  209.  
  210.     > eig(symm(rand(3,3))).val[2]
  211.         0.191
  212.  
  213.     > rand(10,10)[1,3,5;2,4,6]
  214.          0.29      0.411      0.345  
  215.         0.561      0.686     0.0287  
  216.         0.269      0.324       0.57  
  217.  
  218.     4) Function recursion ------------------------------------------
  219.  
  220.     Functions can call themselves recursively. Since a function is
  221.     stored in the same manner as a variable, the function can be
  222.     deleted, or renamed. Therefore, users must be careful not to
  223.     rename functions that call themselves or they must use the
  224.     `$self' keyword.
  225.  
  226.     Example:
  227.  
  228.     > fact = function (f) 
  229.       {
  230.         if(f <= 1) {
  231.           return 1;
  232.         else
  233.           return f*$self(f-1);
  234.         }
  235.       };
  236.     > fact(10)
  237.         3628800
  238.  
  239.     5) Function variable scoping -----------------------------------
  240.  
  241.     All function variables are GLOBAL by default. Since builtin
  242.     and user-functions are treated like ordinary variables this
  243.     ensures that user-functions have full access to existing
  244.     builtin and user functions. If you need local variables, use
  245.     the local statement at the beginning of your function.
  246.  
  247.     Example:
  248.  
  249.     > x = function(y)
  250.      {
  251.        local(i);
  252.        for( i in 1:y.n ) {
  253.          y[i] = 0;
  254.        }
  255.        return y;
  256.      };
  257.     >
  258.  
  259.     The local statement declares `i' to be a local scalar variable
  260.     with initial value UNDEFINED. When the function returns the
  261.     variable `i' will cease to exist. When x() is called again `i'
  262.     will again be re-initialized UNDEFINED. The local statement
  263.     must be the 1st statement in a function, and only one local
  264.     statement is allowed. If you must declare alot of local
  265.     variables, then break the local statement with a continuation.
  266.  
  267.     local(i, j, k,...
  268.            l, m, n);
  269.  
  270.     Local variables are resolved 1st. When a name collision occurs
  271.     between a local variable, and a global variable, including
  272.     builtin functions, the local variable takes precedence.
  273.  
  274.     6) Special Topics ----------------------------------------------
  275.  
  276.         A) Although pass by value is the default behavior for
  277.         function arguments, there are some instances where
  278.         this may not seem true (but it is). For example, when
  279.         you pass part of a matrix into a function you cannot
  280.         modify the original matrix.
  281.  
  282.         > x = function ( a ) { a[1] = pi; }
  283.             <user-function>
  284.         > z=rand(2,2);
  285.         > z
  286.          z =
  287.            0.0369      0.665  
  288.             0.162     0.0847  
  289.         > x(z);
  290.         > z
  291.          z =
  292.              3.14      0.665  
  293.             0.162     0.0847  
  294.         > x(z[2]);
  295.         > z
  296.          z =
  297.              3.14      0.665  
  298.             0.162     0.0847  
  299.         > y
  300.             UNDEFINED
  301.         > x(y=z[2]);
  302.         > y
  303.          y =
  304.              3.14  
  305.  
  306.         You can see that in the first function call, z is
  307.         passed by reference. In the second call, the second
  308.         element of z (z[2]) is copied into a temporary
  309.         variable, which in turn is passed by reference to the
  310.         function. In the last call the temporary variable is
  311.         stored in the variable y, which as you can see, is
  312.         passed by reference to the function for modification.        
  313.  
  314.     ----------------------------------------------------------------
  315.